LCLint User's Guide

Version 2.2
August 1996

David Evans
Systematic Program Development Group
MIT Laboratory for Computer Science

LCLint is a tool for statically checking C programs. With minimal effort, LCLint can be used as a better lint.[1] If additional effort is invested adding annotations to programs, LCLint can perform stronger checks than can be done by any standard lint.

Some problems detected by LCLint include:

• Violations of information hiding. A user-defined type can be declared as abstract, and a message is reported where code inappropriately depends on the representation of the type. (Section 3)

• Inconsistent modification of caller-visible state. Functions can be annotated with information on what caller-visible state may be modified by the function, and an error is reported if the modifications produced by the function contradict its declaration. (Section 4.1)

• Inconsistent use of global variables. Information on what global and file scope variables a function may use can be added to function declarations, and a message is reported if the implementation of the function uses other global variables or does not uses every global variable listed in its declaration. (Section 4.2)

• Memory management errors. Instances where storage that has been deallocated is used, or where storage is not deallocated (memory leaks). (Section 5)

• Dangerous data sharing or unexpected aliasing. Parameters to a function share storage in a way that may lead to undefined or undesired behavior, or a reference to storage within the representation of an abstract type is created. (Section 6)

• Using possibly undefined storage or returning storage that is not completely defined (except as documented). (Section 7.1)

• Dereferencing a possibly null pointer. (Section 7.2)

• Dangerous macro implementations or invocations. (Section 8)

• Violations of customizable naming conventions. (Section 9)

• Program behavior that is undefined because it depends on order of evaluation, likely infinite loops, fall-through cases, incomplete logic, statements with no effect, ignored return values, unused declarations, and exceeding certain standard limits. (Section 10)

LCLint checking can be customized to select what classes of errors are reported using command line flags and stylized comments in the code.

This document is a guide to using LCLint. Section 1 is a brief overview of the design goals of LCLint. Section 2 explains how to run LCLint, interpret messages produce, and control checking. Sections 3-10 describe particular checks done by LCLint.

Contents

1. Overview
2. Operation
   • Messages
   • Flags
   • Stylized Comments
     • Annotations
     • Control Comments
3. Abstract Types
   • Access
   • Mutability
   • Boulean Types
   • Primitive C Types
     • Characters
     • Enumerators
     • Numeric Types
     • Arbitrary Integral Types
4. Function Interfaces
   • Modifications
     • Special Modifications
     • Missing Modifies Clauses
     • Limitations
   • Global Variables
     • Controlling Globals Checking
   • Declaration Consistency
5. Memory Management
   • Storage Model
   • Deallocation Errors
     • Unshared References
     • Temporary Parameters
     • Owned and Dependent References
     • Kept Parameters
     • Stack References
     • Inner Storage
   • Implicit Memory Annotations
   • Reference Counting
6. Sharing
   • Aliasing
     • Unique Parameters
     • Returned Parameters
   • Exposure
     • Read-Only Storage
     • Exposed Storage
7. Value Constraints
   • Use Before Definition
     • Undefined Parameters
     • Relaxing Checking
     • Partially Defined Structures
     • Global Variables
   • Null Pointers
     • Predicate Functions
     • Overriding Null Types
     • Relaxing Null Checking
   • Execution
   • Special Clauses
8. Macros
   • Constant Macros
   • Function-like Macros
     • Side-Effect Free Parameters
     • Polymorphism
   • Controlling Macro Checking
   • Iterators
9. Naming Conventions
   • Type-Based Naming Conventions
     • Czech Names
     • Slovak Names
     • Czechoslovak Names
   • Namespace Prefixes
   • Naming Restrictions
     • Reserved Names
     • Distinct Identifiers
10. Other Checks
    • Undefined Evaluation Order
    • Problematic Control Structures
      • Likely Infinite Loops
      • Switches
      • Deep Breaks
      • Loop and If Bodies
      • Complete if-else Logic
    • Suspicious Statements
      • Statements with No Effects
      • Ignored Return Values
    • Unused Declarations
    • Complete Programs
      • Unnecessary External Names
      • Declarations Missing from Headers
    • Compiler Limits

Appendices

Appendix A. Availability
Appendix B. Communication
Appendix C. Flags
Appendix D. Annotations
Appendix E. Control Comments
Appendix F. Libraries
Appendix G. Specifications
Appendix H. Emacs

Figures

References
Acknowledgements